sdk/samples/all in on code/Visual Studio 2008/CppMailslotServer/CppMailslotServer.cpp

   1 /****************************** Module Header ******************************\
   2 Module Name:  CppMailslotServer.cpp
   3 Project:      CppMailslotServer
   4 Copyright (c) Microsoft Corporation.
   5
   6 Mailslot is a mechanism for one-way inter-process communication in the local
   7 machine or across the computers in the intranet. Any clients can store
   8 messages in a mailslot. The creator of the slot, i.e. the server, retrieves
   9 the messages that are stored there:
  10
  11 Client (GENERIC_WRITE) ---> Server (GENERIC_READ)
  12
  13 This code sample demonstrates calling CreateMailslot to create a mailslot
  14 named "\\.\mailslot\SampleMailslot". The security attributes of the slot are
  15 customized to allow Authenticated Users read and write access to the slot,
  16 and to allow the Administrators group full access to it. The sample first
  17 creates such a mailslot, then it reads and displays new messages in the slot
  18 when user presses ENTER in the console.
  19
  20 This source is subject to the Microsoft Public License.
  21 See http://www.microsoft.com/opensource/licenses.mspx#Ms-PL.
  22 All other rights reserved.
  23
  24 THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND,
  25 EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED
  26 WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR PURPOSE.
  27 \***************************************************************************/
  28
  29 #pragma region Includes
  30 #include <stdio.h>
  31 #include <windows.h>
  32 #include <assert.h>
  33 #include <sddl.h>
  34 #pragma endregion
  35
  36
  37 BOOL ReadMailslot(HANDLE hMailslot);
  38 BOOL CreateMailslotSecurity(PSECURITY_ATTRIBUTES *ppSa);
  39 void FreeMailslotSecurity(PSECURITY_ATTRIBUTES pSa);
  40
  41
  42 int wmain(int argc, wchar_t *argv[])
  43 {
  44     // The name of the mailslot. It is in the form of \\.\mailslot\[path]name
  45     // The name field must be unique. The name may include multiple levels of
  46     // pseudo directories separated by backslashes. For example, both
  47     // \\.\mailslot\mailslot_name and \\.\mailslot\abc\def\ghi are valid.
  48     const PCWSTR MAILSLOT_NAME = L"\\\\.\\mailslot\\SampleMailslot";
  49
  50     DWORD dwError = ERROR_SUCCESS;
  51     PSECURITY_ATTRIBUTES pSa = NULL;
  52     HANDLE hMailslot = INVALID_HANDLE_VALUE;
  53
  54     // Prepare the security attributes (the lpSecurityAttributes parameter in
  55     // CreateMailslot) for the mailslot. This is optional. If the
  56     // lpSecurityAttributes parameter of CreateMailslot is NULL, the mailslot
  57     // gets a default security descriptor and the handle cannot be inherited.
  58     // The ACLs in the default security descriptor of a mailslot grant full
  59     // control to the LocalSystem account, (elevated) administrators, and the
  60     // creator owner. They also give only read access to members of the
  61     // Everyone group and the anonymous account. However, if you want to
  62     // customize the security permission of the mailslot, (e.g. to allow
  63     // Authenticated Users to read from and write to the pipe), you need to
  64     // create a SECURITY_ATTRIBUTES structure.
  65     if (!CreateMailslotSecurity(&pSa))
  66     {
  67         dwError = GetLastError();
  68         wprintf(L"CreateMailslotSecurity failed w/err 0x%08lx\n", dwError);
  69         goto Cleanup;
  70     }
  71
  72     // Create the mailslot.
  73     hMailslot = CreateMailslot(
  74         MAILSLOT_NAME,              // The name of the mailslot
  75         0,                          // No maximum message size
  76         MAILSLOT_WAIT_FOREVER,      // No time-out for operations
  77         pSa                         // Security attributes
  78         );
  79
  80     if (hMailslot == INVALID_HANDLE_VALUE)
  81     {
  82         dwError = GetLastError();
  83         wprintf(L"Unable to create mailslot w/err 0x%08lx\n", dwError);
  84         goto Cleanup;
  85     }
  86
  87     wprintf(L"The mailslot (%s) is created.\n", MAILSLOT_NAME);
  88
  89     // Check messages in the mailslot.
  90     wprintf(L"Press ENTER to check new messages or press Q to quit ...");
  91     char cmd = getchar();
  92     while (cmd != 'Q' && cmd != 'q')
  93     {
  94         if (cmd == '\n')
  95         {
  96             wprintf(L"Checking new messages...\n");
  97             ReadMailslot(hMailslot);
  98
  99             wprintf(L"Press ENTER to check new messages or press Q to quit ...");
 100         }
 101         cmd = getchar();
 102     }
 103
 104 Cleanup:
 105     // Centralized cleanup for all allocated resources.
 106     if (pSa != NULL)
 107     {
 108         FreeMailslotSecurity(pSa);
 109         pSa = NULL;
 110     }
 111     if (hMailslot != INVALID_HANDLE_VALUE)
 112     {
 113         CloseHandle(hMailslot);
 114         hMailslot = INVALID_HANDLE_VALUE;
 115     }
 116
 117     return 0;
 118 }
 119
 120
 121 //
 122 //   FUNCTION: ReadMailslot(HANDLE);
 123 //
 124 //   PURPOSE: Read the messages from a mailslot by using the mailslot handle
 125 //   in a call to the ReadFile function.
 126 //
 127 //   PARAMETERS:
 128 //      * hMailslot - The handle of the mailslot.
 129 //
 130 BOOL ReadMailslot(HANDLE hMailslot)
 131 {
 132     assert(hMailslot != INVALID_HANDLE_VALUE);
 133
 134     DWORD cbMessageBytes = 0;       // Size of the message in bytes
 135     DWORD cbBytesRead = 0;          // Number of bytes read from the slot
 136     DWORD cMessages = 0;            // Number of messages in the mailslot
 137     DWORD nMessageId = 0;           // Message ID
 138
 139     BOOL fSucceeded = FALSE;
 140
 141     PWSTR pszBuffer;                // A buffer used to store one message
 142
 143     // Check for the number of messages in the mailslot.
 144     fSucceeded = GetMailslotInfo(
 145         hMailslot,                  // Handle of the mailslot
 146         NULL,                       // No maximum message size
 147         &cbMessageBytes,            // Size of next message
 148         &cMessages,                 // Number of messages
 149         NULL                        // No read time-out
 150         );
 151     if (!fSucceeded)
 152     {
 153         wprintf(L"GetMailslotInfo failed w/err 0x%08lx\n", GetLastError());
 154         return fSucceeded;
 155     }
 156
 157     if (cbMessageBytes == MAILSLOT_NO_MESSAGE)
 158     {
 159         // There are no new messages in the mailslot at present.
 160         wprintf(L"No new messages.\n");
 161         return fSucceeded;
 162     }
 163
 164     // Retrieve the messages one by one from the mailslot.
 165     while (cMessages != 0)
 166     {
 167         nMessageId++;
 168
 169         // Allocate the memory for the message based on its size info,
 170         // cbMessageBytes, which was retrieved from GetMailslotInfo.
 171         pszBuffer = (PWSTR)LocalAlloc(LPTR, cbMessageBytes);
 172         if (NULL == pszBuffer)
 173         {
 174             fSucceeded = FALSE;
 175             break;
 176         }
 177
 178         // Read from the mailslot.
 179         fSucceeded = ReadFile(
 180             hMailslot,              // Handle of the slot
 181             pszBuffer,              // Buffer to receive data
 182             cbMessageBytes,         // Size of buffer in bytes
 183             &cbBytesRead,           // Number of bytes read
 184             NULL                    // Not overlapped I/O
 185             );
 186         if (!fSucceeded)
 187         {
 188             wprintf(L"ReadFile failed w/err 0x%08lx\n", GetLastError());
 189             LocalFree(pszBuffer);
 190             break;
 191         }
 192
 193         // Display the message.
 194         wprintf(L"Message #%ld: %s\n", nMessageId, pszBuffer);
 195
 196         LocalFree(pszBuffer);
 197
 198         // Get the current number of un-read messages in the slot. The number
 199         // may not equal the initial message number because new messages may
 200         // arrive while we are reading the items in the slot.
 201         fSucceeded = GetMailslotInfo(
 202             hMailslot,              // Handle of the mailslot
 203             NULL,                   // No maximum message size
 204             &cbMessageBytes,        // Size of next message
 205             &cMessages,             // Number of messages
 206             NULL                    // No read time-out
 207             );
 208         if (!fSucceeded)
 209         {
 210             wprintf(L"GetMailslotInfo failed w/err 0x%08lx\n", GetLastError());
 211             break;
 212         }
 213     }
 214
 215     return fSucceeded;
 216 }
 217
 218
 219 //
 220 //   FUNCTION: CreateMailslotSecurity(PSECURITY_ATTRIBUTES *)
 221 //
 222 //   PURPOSE: The CreateMailslotSecurity function creates and initializes a
 223 //   new SECURITY_ATTRIBUTES structure to allow Authenticated Users read and
 224 //   write access to a mailslot, and to allow the Administrators group full
 225 //   access to the mailslot.
 226 //
 227 //   PARAMETERS:
 228 //   * ppSa - output a pointer to a SECURITY_ATTRIBUTES structure that allows
 229 //     Authenticated Users read and write access to a mailslot, and allows
 230 //     the Administrators group full access to the mailslot. The structure
 231 //     must be freed by calling FreeMailslotSecurity.
 232 //
 233 //   RETURN VALUE: Returns TRUE if the function succeeds.
 234 //
 235 //   EXAMPLE CALL:
 236 //
 237 //     PSECURITY_ATTRIBUTES pSa = NULL;
 238 //     if (CreateMailslotSecurity(&pSa))
 239 //     {
 240 //         // Use the security attributes
 241 //         // ...
 242 //
 243 //         FreeMailslotSecurity(pSa);
 244 //     }
 245 //
 246 BOOL CreateMailslotSecurity(PSECURITY_ATTRIBUTES *ppSa)
 247 {
 248     BOOL fSucceeded = TRUE;
 249     DWORD dwError = ERROR_SUCCESS;
 250
 251     PSECURITY_DESCRIPTOR pSd = NULL;
 252     PSECURITY_ATTRIBUTES pSa = NULL;
 253
 254     // Define the SDDL for the security descriptor.
 255     PCWSTR szSDDL = L"D:"       // Discretionary ACL
 256         L"(A;OICI;GRGW;;;AU)"   // Allow read/write to authenticated users
 257         L"(A;OICI;GA;;;BA)";    // Allow full control to administrators
 258
 259     if (!ConvertStringSecurityDescriptorToSecurityDescriptor(szSDDL,
 260         SDDL_REVISION_1, &pSd, NULL))
 261     {
 262         fSucceeded = FALSE;
 263         dwError = GetLastError();
 264         goto Cleanup;
 265     }
 266
 267     // Allocate the memory of SECURITY_ATTRIBUTES.
 268     pSa = (PSECURITY_ATTRIBUTES)LocalAlloc(LPTR, sizeof(*pSa));
 269     if (pSa == NULL)
 270     {
 271         fSucceeded = FALSE;
 272         dwError = GetLastError();
 273         goto Cleanup;
 274     }
 275
 276     pSa->nLength = sizeof(*pSa);
 277     pSa->lpSecurityDescriptor = pSd;
 278     pSa->bInheritHandle = FALSE;
 279
 280     *ppSa = pSa;
 281
 282 Cleanup:
 283     // Clean up the allocated resources if something is wrong.
 284     if (!fSucceeded)
 285     {
 286         if (pSd)
 287         {
 288             LocalFree(pSd);
 289             pSd = NULL;
 290         }
 291         if (pSa)
 292         {
 293             LocalFree(pSa);
 294             pSa = NULL;
 295         }
 296
 297         SetLastError(dwError);
 298     }
 299
 300     return fSucceeded;
 301 }
 302
 303
 304 //
 305 //   FUNCTION: FreeMailslotSecurity(PSECURITY_ATTRIBUTES)
 306 //
 307 //   PURPOSE: The FreeMailslotSecurity function frees a SECURITY_ATTRIBUTES
 308 //   structure that was created by the CreateMailslotSecurity function.
 309 //
 310 //   PARAMETERS:
 311 //   * pSa - pointer to a SECURITY_ATTRIBUTES structure that was created by
 312 //     the CreateMailslotSecurity function.
 313 //
 314 void FreeMailslotSecurity(PSECURITY_ATTRIBUTES pSa)
 315 {
 316     if (pSa)
 317     {
 318         if (pSa->lpSecurityDescriptor)
 319         {
 320             LocalFree(pSa->lpSecurityDescriptor);
 321         }
 322         LocalFree(pSa);
 323     }
 324 }